Skip to content

feat(vz): 動態解析度 HiDPI output scale——翻為 macOS 14+ 預設#129

Merged
TimLai666 merged 4 commits into
mainfrom
claude/optimistic-gould-c16177
Jul 12, 2026
Merged

feat(vz): 動態解析度 HiDPI output scale——翻為 macOS 14+ 預設#129
TimLai666 merged 4 commits into
mainfrom
claude/optimistic-gould-c16177

Conversation

@TimLai666

Copy link
Copy Markdown
Owner

Summary

  • guest-agent 的 resize watcher 新增 HiDPI output scale:host(vz-helper)把螢幕 backingScaleFactor 經 kernel cmdline chefer.gui_scale= 傳入 guest,watcher 開機補設一次、每次 re-modeset 同一次 apply 一併帶 --scale,解決動態解析度模式下 Retina 實體像素尺寸讓 Linux guest UI/游標縮半的問題。
  • BREAKING(macOS 14+ GUI 預設行為改變)CHEFER_VZ_DYNAMIC_RESOLUTION 語義翻轉為預設開啟真動態解析度;=0(或 macOS 13、舊 cage <0.2.0 overlay)退回原本的 view 等比縮放+鎖長寬比保底路徑。
  • DESIGN §6 ④ / README / HANDOFF-macos-vz / vz-smoke.sh --gui 清單同步更新為已翻預設狀態。
  • 記錄一則 follow-up:vz bridge 出網(pasta→apk)在驗證當下環境不通,待換網路重跑分辨是環境因素還是 container-DNS 回歸。

實機驗證(Apple Silicon,macOS 26,2026-07-12)

機器可驗項:

  • 開機:console gui: resize: Virtual-1 output scale -> 2,guest 內 xdpyinfo 回報邏輯尺寸 1280x800(實體模式 2560x1600)
  • 縮放:gui: resize: Virtual-1 -> 2200x1400 (scale 2),xdpyinfo 跟隨 1100x700
  • 翻預設後兩條路徑各跑一輪:預設路徑全程零筆實體像素尺寸;=0 opt-out 全程 1280x800 點數模式,與舊預設行為一致

人工目測項(xeyes/xclock):

  • 游標與 UI 尺寸正常、非縮半
  • xeyes 眼珠準確跟隨游標(絕對座標映射正確)
  • Xwayland 放大畫質可接受
  • 拖拉視窗的細黑邊為 re-modeset debounce(400ms)前的暫態,放手即消失

Test plan

  • cargo test -p guest-agent(Linux 容器,含新增的 gui_scale 解析、mode_args 旗標測試)
  • cargo check / cargo clippy -p guest-agent(aarch64-unknown-linux-musl)
  • build-vz-helper.sh 編譯+entitlement 簽章
  • 實機 e2e:動態解析度預設路徑 + opt-out 路徑,各含 xdpyinfo 自動化取樣
  • 實機人工目測:游標/UI 尺寸、座標映射、畫質、拖拉黑邊
  • CI 全綠(等待)

🤖 Generated with Claude Code

TimLai666 and others added 4 commits July 12, 2026 00:48
…設 cage 縮放(待實機)

CHEFER_VZ_DYNAMIC_RESOLUTION=1 推進 guest 的是 Retina 實體像素尺寸,Linux
guest 無 HiDPI 概念 → 游標/UI 縮半(實機已確認;DESIGN §6 ④ 記為翻預設的
前置缺口)。本次補上縮放這半段:

- vz-helper:動態解析度模式(macOS 14+ + GUI)把開機當下螢幕的
  backingScaleFactor 以 chefer.gui_scale= 附進 kernel cmdline(同 clip_token
  作法;scale 1 不附、跨螢幕拖移的 scale 變化不追、恆用開機值)。
- guest-agent resize watcher:照 clipboard.rs 的 read_cmdline 模式解析
  chefer.gui_scale(僅收 (1,4] 有限值,0/負/NaN/離譜值一律不採——不把會毀
  版面的值餵給 compositor);啟動時對現行輸出補設一次 output scale(開機
  初始模式就已是像素尺寸、之後未必再有 drm 事件),此後每次
  wlr-randr --custom-mode 同一次 apply 一併帶 --scale(cage 0.2.0 的
  wlr-output-management apply 走 wlr_output_head_v1_state_apply,支援
  scale)。未附參數(WHP、vz 預設模式)完全不帶 --scale,路徑與既往相同
  (mode_args 單元測試鎖住)。

邏輯尺寸回到「點」數:游標/UI 尺寸正常,X11 surface 由 compositor 放大——
預期視覺等同預設 view-scaling,但比例自由、無 letterbox。待實機驗證三變因
(vz-smoke --gui 清單已列):Xwayland 在 scaled output 的品質、絕對座標輸
入映射、xdpyinfo 應回報邏輯尺寸(1100x700 而非 2200x1400)。全數通過後依
DESIGN §6 ④ 評估把 CHEFER_VZ_DYNAMIC_RESOLUTION 翻成預設。

驗證:guest-agent 55 測試於 Linux 容器全過(含新增 gui_scale 解析、
mode_args 旗標測試);aarch64-musl cargo check/clippy 乾淨;
build-vz-helper.sh 編譯+簽章成功。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
實機 e2e(Apple Silicon,macOS 26;xdpyinfo probe 容器 + 動態解析度 +
CHEFER_VZ_GUI_TEST_RESIZE=30:1100x700):

- 開機:console「gui: resize: Virtual-1 output scale -> 2」,guest 內
  xdpyinfo 回報邏輯尺寸 1280x800(實體模式 2560x1600)——啟動補設 scale
  的必要性成立(開機初始模式即 Retina 像素尺寸,其後無 drm 事件)。
- t+30s 程式化縮放:「gui: resize: Virtual-1 -> 2200x1400 (scale 2)」,
  xdpyinfo 跟隨 1100x700。cage 0.2.0 對 mode+scale 同次 apply 無誤。
- 全程 40 筆取樣(15 筆 1280x800、25 筆 1100x700)零筆出現實體像素尺寸;
  app 於 probe 結束後以 exit 0 乾淨收攤(介面服務 exit 0 → 收 app 語意)。

翻預設前僅剩人工目測項:游標/UI 尺寸視覺確認、Xwayland 放大畫質、點擊
落點——vz-smoke --gui 清單已改列目測項。DESIGN §6 ④ / HANDOFF / README
狀態同步。

另記:本次 guest 出網(pasta bridge → apk)在測試當下環境不通
(dl-cdn「temporary error」,host 直連同 URL 正常),與本改動無關、
先前已實機驗證過 bridge 出網——驗證改用 docker save 預裝 xdpyinfo 的
tar image(network: internal)排除網路變因。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…NS 回歸待分辨)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
DESIGN §6 ④ 翻預設條件全數成立(Apple Silicon 實機,2026-07-12):
- 機器可驗項(前一輪):cmdline chefer.gui_scale=2 → 開機補設 output scale、
  換模式同 apply 帶 --scale、xdpyinfo 全程回報邏輯尺寸。
- 人工目測項(本輪,xeyes/xclock 實測):游標與 UI 尺寸正常非縮半、眼珠
  跟隨游標=絕對座標映射正確、Xwayland 放大畫質可接受、拖拉時細黑邊
  確認為 re-modeset debounce(400ms)前的暫態、放手即消失。

vz-helper:CHEFER_VZ_DYNAMIC_RESOLUTION 預設值翻轉——macOS 14+ 未設或非 0
即走真動態解析度;=0(或 macOS 13)退回原 view 等比縮放+鎖長寬比,作為
搭配舊 overlay(cage <0.2.0、guest 不 re-modeset)時的保底路徑。正常 kit
的 helper 與 overlay 同版出貨,不會出現新 helper 配舊 overlay 的組合。

翻轉後實機回歸(xdpyinfo probe,兩條路各一輪):
- 預設(無環境變數):output scale -> 2、resize -> 2200x1400 (scale 2)、
  xdpyinfo 1280x800 → 1100x700、零筆實體像素尺寸、exit 0。
- opt-out(=0):零筆 scale 相關 console 行、全程 1280x800 點數模式、
  exit 0——與舊預設行為一致。

DESIGN / README / HANDOFF / vz-smoke --gui 清單同步改為「已翻預設+回歸
清單」。BREAKING:macOS 14+ 的 GUI 預設行為改變(視窗自由比例、真解析度
跟隨);不想要時設 CHEFER_VZ_DYNAMIC_RESOLUTION=0。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@TimLai666
TimLai666 merged commit 78ebd1b into main Jul 12, 2026
18 checks passed
@TimLai666
TimLai666 deleted the claude/optimistic-gould-c16177 branch July 12, 2026 03:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant